<?xml version='1.0' encoding='UTF-8' ?>
<ui:composition template="template-without-sidebar.xhtml" xmlns="http://www.w3.org/1999/xhtml"
                xmlns:ui="http://java.sun.com/jsf/facelets"
                xmlns:h="http://java.sun.com/jsf/html"
                xmlns:f="http://java.sun.com/jsf/core"
                xmlns:ice="http://www.icesoft.com/icefaces/component"
                xmlns:odr="http://java.sun.com/jsf/composite/odr"
                xmlns:c="http://java.sun.com/jsp/jstl/core">

    <ui:define name="head">
    </ui:define>

    <ui:define name="pagetitle">
        Web service
    </ui:define>

    <ui:define name="content">
            <h1>Web service</h1>
            <p>
                You can use the following web services to retrieve information
                from the ODR.
            </p>
            <p>
                Please note that all URLs are relative to the domain which
                hosts the web service.
            </p>
            
            <h2>Resources</h2>
            <p>
                The following resources are available over a RESTful web-service.
                Please prepend the URL <em>/web-service/rest</em> to the URLs which are
                listed in the table. Example use cases are listed in the next
                section.
            </p>
            <p>
                All resources can produce media types
                <em>application/xml</em> and
                <em>application/json</em>.
                HTTP <span class="post">POST</span>, <span class="put">PUT</span> and
                <span class="delete">DELETE</span> resources only accept 
                <em>application/xml</em>. Also,
                please note that the web service <strong>expects UTF-8 encoding</strong>!
            </p>
            <p>
                A resource's description may contain an XML example which uses 
                a notation similar to regular expressions, e.g., \d+ denotes one or
                more numbers. \type and \state refer to one of the relationship
                type names, respectively decision state names. Valid names can
                be requested through the <a href="/web-service/rest/decisionstates" title="Try the web service">decision states</a>
                and <a href="/web-service/rest/relationshiptypes" title="Try the web service">relationship types</a>
                resource methods. Dates can be passed in the xsd:dateTime format
                <em>yyyy-MM-ddTHH:mm:ss</em>. Examples refer
                to dates with \date.
            </p>
            <table class="webServiceDescription">
                <thead>
                    <tr>
                        <th>Method</th>
                        <th>URL</th>
                        <th>Authentication</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td class="get">GET</td>
                        <td>
                            <a href="/web-service/rest/decisionstates"
                               title="Try the web service">
                                decisionstates
                            </a>
                        </td>
                        <td class="anonUser">Anonymous</td>
                        <td>
                            Get a list of all common decision-states which
                            are existing in the ODR.
                        </td>
                    </tr>
                    <tr>
                        <td class="get">GET</td>
                        <td>
                            <a href="/web-service/rest/relationshiptypes"
                               title="Try the web service">
                                relationshiptypes
                            </a>
                        </td>
                        <td class="anonUser">Anonymous</td>
                        <td>
                            Get a list of all common relationship-types which
                            are existing in the ODR.
                        </td>
                    </tr>
                    <tr>
                        <td class="get">GET</td>
                        <td>
                            <a href="/web-service/rest/user/projects"
                               title="Try the web service">
                                user/projects
                            </a>
                        </td>
                        <td class="authUser">Authenticated user</td>
                        <td>
                            Retrieve an overview over all the projects in which
                            a user is involved. The user is identified through
                            the user authentication.
                        </td>
                    </tr>
                    <tr>
                        <td class="get">GET</td>
                        <td>projects/{projectId}</td>
                        <td class="groupUser">Group member</td>
                        <td>
                            Retrieve details for a project. The project is
                            identified by the project id which is appended to the
                            URL, e.g., <span class="italics">project/10</span>.
                        </td>
                    </tr>
                    <tr>
                        <td class="get">GET</td>
                        <td>projects/{projectId}/export/tex</td>
                        <td class="groupUser">Group member</td>
                        <td>
                            Export all project information to a TeX format. The
                            result will be a ZIP file containing multiple TeX
                            files. Example: <span class="italics">project/10/export/tex</span>.
                        </td>
                    </tr>
                    <tr>
                        <td class="get">GET</td>
                        <td>projects/{projectId}/decisions/{decisionId}</td>
                        <td class="groupUser">Group member</td>
                        <td>
                            Retrieve details for a single decision. The decision is
                            identified by the project id and the decision id, which are appended to the
                            URL e.g., <span class="italics">project/10/decisions/12</span>.
                        </td>
                    </tr>
                    <tr>
                        <td class="post">POST</td>
                        <td>projects/{projectId}/decisions</td>
                        <td class="groupUser">Group member</td>
                        <td>
                            Add a new decision to the project. Example URL: <span class="italics">project/10/decisions</span>.
                            The request entity needs to be in the following format.
<pre class="prettyprint">
&lt;editdecision&gt;
    &lt;name&gt;<span class="regex">.+</span>&lt;/name&gt;
    &lt;decidedWhen&gt;<span class="regex">\date</span>&lt;/decidedWhen&gt;
    &lt;documentedWhen&gt;<span class="regex">\date</span>&lt;/documentedWhen&gt;
    &lt;state&gt;<span class="regex">\state</span>&lt;/state&gt;
    <span class="comment">&lt;!-- you may use zero or more relationshipDTOs elements --&gt;</span>
    &lt;relationshipDTOs id="<span class="regex">\d+</span>"&gt;
        &lt;relationshipType&gt;<span class="regex">\type</span>&lt;/relationshipType&gt;
        &lt;targetId&gt;<span class="regex">\d+</span>&lt;/targetId&gt; <span class="comment">&lt;!-- target decision id --&gt;</span>
    &lt;/relationshipDTOs&gt;
&lt;/editdecision&gt;
</pre>
                        </td>
                    </tr>
                    <tr>
                        <td class="put">PUT</td>
                        <td>projects/{projectId}/decisions/{decisionId}</td>
                        <td class="groupUser">Group member</td>
                        <td>
                            Update an existing decision. Example URL: <span class="italics">project/10/decisions/12</span>.
                            The request entity needs to be in the following format.
<pre class="prettyprint">
&lt;editdecision&gt;
    &lt;id&gt;<span class="regex">\d+</span>&lt;/id&gt;
    &lt;name&gt;<span class="regex">.+</span>&lt;/name&gt;
    &lt;decidedWhen&gt;<span class="regex">\date</span>&lt;/decidedWhen&gt;
    &lt;documentedWhen&gt;<span class="regex">\date</span>&lt;/documentedWhen&gt;
    &lt;state&gt;<span class="regex">\state</span>&lt;/state&gt;
    <span class="comment">&lt;!-- you may use zero or more relationshipDTOs elements --&gt;</span>
    &lt;relationshipDTOs id="<span class="regex">\d+</span>"&gt;
        &lt;relationshipType&gt;<span class="regex">\type</span>&lt;/relationshipType&gt;
        &lt;targetId&gt;<span class="regex">\d+</span>&lt;/targetId&gt; <span class="comment">&lt;!-- target decision id --&gt;</span>
    &lt;/relationshipDTOs&gt;
&lt;/editdecision&gt;
</pre>
                        </td>
                    </tr>
                    <tr>
                        <td class="post">POST</td>
                        <td>projects/{projectId}/ratings</td>
                        <td class="groupUser">Group member</td>
                        <td>
                            Add or update decision ratings, i.e., a decision rated in respect of a certain concern.
                            For instance, <span class="italics">project/10/ratings</span>. The request entity needs to be
                            in the following format. To update a rating, no id is required. Instead, the concern and decision
                            id will be used for identification.
<pre class="prettyprint">&lt;rating&gt;
    &lt;concernId&gt;<span class="regex">\d+</span>&lt;/concernId&gt;
    &lt;decisionId&gt;<span class="regex">\d+</span>&lt;/decisionId&gt;
    &lt;effect&gt;<span class="regex">(EXCLUDED|VERYNEGATIVE|NEGATIVE|NEUTRAL|POSITIVE|VERYPOSITIVE|REQUIRED)</span>&lt;/effect&gt;
&lt;/rating&gt;
</pre>
                        </td>
                    </tr>
                </tbody>
            </table>

            <h2>Example</h2>
            <p>
                The following HTTP request shows how an overview of all projects
                (in which a user is involved) can be retrieved and how the user
                is authenticated. For authentication purposes, the user's email
                address and his password are expected for authentication
                (separated by a colon and base 64 encoded).
            </p>
<pre class="prettyprint small">GET /web-service/rest/user/projects HTTP/1.1
Host: www.decisionrepository.com
Accept: application/xml
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==</pre>
            <p>
                This request retrieves details about a project, i.e. decisions,
                their relationships and history. Again, user authentication is
                required and the user must be member of the group for which the
                data should be retrieved. In this case the web service will
                produce a JSON result.
            </p>
<pre class="prettyprint small">GET /web-service/rest/projects/10 HTTP/1.1
Host: www.decisionrepository.com
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==</pre>
            <p>
                At last, this request adds a decision rating. It shows how
                XML data can be send to the server.
            </p>
<pre class="prettyprint small">
POST /web-service/rest/projects/10/ratings HTTP/1.1
Host: www.decisionrepository.com
Content-Type: application/xml; charset=UTF-8
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

&lt;rating&gt;
    &lt;concernId&gt;42&lt;/concernId&gt;
    &lt;decisionId&gt;101010&lt;/decisionId&gt;
    &lt;effect&gt;VERYPOSITIVE&lt;/effect&gt;
&lt;/rating&gt;
</pre>
            <h2>Usage</h2>
            <p>
                You can make use of some Java classes which we provide to simplify
                the development of web service clients. The library can be retrieved
                easily using the following
                <a href="http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22nl.rug.search%22%20AND%20a%3A%22web-service-client%22">
                    Maven dependency</a>
                information. Alternatively, you may also use the
                <a href="/web-service/rest-schema">
                    schema file
                </a>
                (see also JAX-B, xjc command line tool). A simple Maven project
                for demonstration purposes is also
                <a href="https://github.com/bripkens/Example-ODR-web-service-client" title="Check out the sample project">available on GitHub</a>.
            </p>
<pre class="prettyprint small">&lt;dependency&gt;
    &lt;groupId&gt;nl.rug.search&lt;/groupId&gt;
    &lt;artifactId&gt;web-service-client&lt;/artifactId&gt;
    &lt;version&gt;0.2.4&lt;/version&gt;
&lt;/dependency&gt;</pre>
    </ui:define>

</ui:composition>
